Integration Guide Estun LS 1.5
This guide describes how to integrate Estun robots with Locator Studio (LS) 1.5.
For the general concept of the communication, see the Robot communication overview. The supported versions of all Robot modules are listed in the Robot module support matrix.
1. Prerequisites
Before you start, make sure that your system meets these requirements:
Controller software version 1.36 or higher
ARM Linux CPU
Locator Studio 1.5
This version of the Robot module was developed on an Estun Linux controller with software V1.36.C09.R10.A.
Optional: to commission the robot from a PC, install Estun Editor (version 2.7.4.1 or higher is recommended). The robot firmware and Estun Editor are free to download from the Estun support website.
2. Robot Controller Setup
2.1 Initial Setup and Configuration
For detailed information about the Estun robot controller, see the official Estun documentation. The images below show the ERC3-C1 robot controller used in this manual:
2.2 Network Configuration
The Estun robot controller has several Ethernet ports. Ethernet 2 and Ethernet 3 are reserved for user TCP/IP socket connections. You can use either of them. This manual uses Ethernet 3 for the communication with the Photoneo vision controller.
To change the IP configuration, click Home → Advanced Set → Network.
Enter the IP address and the subnet mask of the robot controller. You can use the IP address of the vision controller as the gateway. This manual uses IP address 192.168.1.2 and subnet mask 255.255.255.0.
Click the Save button to confirm the changes.
Note
The subnet mask 255.255.255.0 is the same as a 24-bit subnet mask (/24). For other combinations, see this table: https://dnsmadeeasy.com/support/subnet
Example of a matching network configuration on the vision controller side:
Vision controller IPv4 address: 192.168.1.1 / 24
Robot controller IPv4 address: 192.168.1.2 / 24 (as configured in the previous step)
You can also use the Test Connection button on the Network page of the vision controller to ping the Estun robot controller.
Based on the result of the test (ping command), a Robot Available or Robot Unavailable message is shown. If the robot is unavailable, check the cables and the network configuration.
2.3 Second Network Interface for Estun Editor (optional)
We recommend that you configure a second port (in this manual, Ethernet 2) for remote access from Estun Editor on a PC. To prevent network conflicts, give this port a static IP address on a different subnet than the one used for the connection to the vision controller.
Example of a valid configuration for this port:
IP Address: 192.168.100.2
Subnet Mask: 255.255.255.0
Example IPv4 configuration of the PC with Estun Editor: 192.168.100.1 / 255.255.255.0
If the connection to the Estun robot fails, or if the controller data structure is not visible after the connection, close Estun Editor and start it again with the Run As Administrator option. Estun Editor should then show this structure:
2.4 Tool TCP Setup
The tool setup is more important for Locator Studio than for Bin Picking Studio. Bin Picking Studio works with a zero tool and compensates for the tool offset in software. The general rule for Locator Studio: do all scanning and calibration with the zero tool frame (nullTool), and do all picking with the real tool. This manual uses a global tool named “toolPhotoneo” with a Z offset of 110 mm.
On Estun robots, the tool configuration is in Menu → Data → Global → Tool.
To change the tool, use the SetTool command with a Tool variable, for example SetTool(nullTool). Change the tool whenever you need to force the correct tool frame. CalibAddPointRequest, CaptureRequest and ScanRequest (with HAND_EYE_ENABLE = true) select nullTool themselves before they read the flange pose. When you pick objects from the Get Objects result, use the real tool. The example programs pass Tool=t_g.toolPhotoneo in every pick and drop motion.
2.5 Importing the Locator Studio Module
The Photoneo Estun LS module (Photoneo_LS_Module_1_5_0.zip) contains:
ESTUN_LS_1_5_0.er - the Estun project: global project variables (
prjglobal.erd), request programs and example programs (each program is an.erpfile with its local variables in the matching.erdfile)README, CHANGELOG, this integration guide (PDF) and a cheat sheet (PDF)
The LS module does not contain the Robot State Server (see section 2.6).
The default way to import the Photoneo Estun LS module to the robot is with a USB flash drive.
First, copy the ESTUN_LS_1_5_0.er folder to your USB drive. On the Estun teach pendant, go to the Project menu, scroll down the sidebar and select the Loader button. The file transfer window opens.
Select the ESTUN_LS_1_5_0.er folder on the USB drive and click the Transfer button to start the copy. All files in the folder are copied to the Estun robot controller.
If there are no errors, you can load the ESTUN_LS_1_5_0 project directly.
After loading, the status of the project in the Project List is “loaded”. To run a program, select it in Playback mode and click “PC” so that it starts from the first line. A program configured with the “self-start” function loads automatically when the user enables the remote mode.
Note
The Estun LS module uses global variables that are not copied during the import. This prevents overwriting existing configurations on customer robots. Add the following variables to the global variable list:
g.PHOTONEO_POSES (CPOS array) - received object poses. The array needs at least as many elements as the highest
NUM_TAR_REQthat you use (15 in PhoMainBasic).g.toolPhotoneo (TOOL) - your real tool, used by the example programs for picking
g.ventil (DO) - gripper output, used by the example programs
After the import, you can synchronize Estun Editor with the robot controller and edit the programs on the PC. Note that, as of April 2026, Estun Editor has some limitations: not all commands can be added or modified correctly in Estun Editor. If a command causes problems, comment out the line and create it again on the teach pendant.
2.6 Robot State Server (optional)
The Robot State Server sends the current joint positions and the Cartesian flange pose of the robot to the vision controller (port 11004, approximately 30 Hz). Locator Studio uses it to show the real robot pose and the tool pose during calibration. Install it if you use a hand-eye (robot-mounted) sensor or if you want to see the robot in Locator Studio.
The Robot State Server is not part of the LS module. Take the files PhoStateServer.py and runpythonRobotFace.sh from the ESTUN_STATE_SERVER folder of the Photoneo Estun BPS 1.12 module. Install them exactly as described in Estun BPS - Installing the Robot State Server:
Connect to the controller with an SFTP client (login root, password ERC654321).
Copy both files to /opt/runtime/python/sdk/libs/RobotFace/ and set their permissions to 0777.
Add the start commands to the end of /opt/runtime/startSys.cmd.
Reboot the controller.
Note
For hand-eye scans, the module can also send the robot pose with every Scan request. To do this, set HAND_EYE_ENABLE = true (see section 3.3).
3. Robot Module
Note
We strongly recommend that you read the Photoneo robotic API before this section.
3.1 Connection to Photoneo Vision Controller
Note
Each main program connects to the Action Request Server on the vision controller when it starts. Three project variables are important for this step:
PHOTONEO_IP - IP address of the vision controller port (default 192.168.1.1)
PHOTONEO_PORT - Port number of the Action Request Server (default 11003)
ESTUN_ID - STRING robot identifier (brand ID)
ESTUN/L/1.5.0XXXXXXXXXXX[DO NOT CHANGE]
In the project STRING variables, set PHOTONEO_IP to the IP address of your vision controller. In this manual, it is 192.168.1.1.
The main program opens the connection with SocketCreate on the socket PhotoneoSocket and sends ESTUN_ID with SocketSendStr. The connection stays open until the program closes it with SocketClose at the label prog_end.
The Estun module uses a text protocol. The robot sends every request as one line of numbers separated by spaces. The vision controller answers with comma-separated lines (header, sub-header, data). The robot confirms every received line with ACK.
You can send requests to the vision controller only after the connection is established. When the program on the Estun controller starts and connects, the Deployment page shows green Connected indicators (see the image below):
3.2 Request List
This section describes the API calls of the Robot module. Use these procedures for high-level control of the locator application. Each procedure is a program in the ESTUN_LS_1_5_0 project. Start it with CALL <Program Name>. Set the input variables before the call. The p. prefix marks project variables (prjglobal.erd) and g. marks global variables. For details about each request, see Action requests.
Note
These procedures are part of the communication backend. Do not edit them.
Request |
ID |
Program Name |
Input |
Populates |
|---|---|---|---|---|
25 |
StartCalibRequest |
INT p.SOL_ID, INT p.VS_ID |
INT p.ERROR_DATA |
|
5 |
CalibAddPointRequest |
CPOS p.CurrentFlangePos (read at call time with nullTool) |
INT p.ERROR_DATA |
|
27 |
SaveCalibRequest |
None |
INT p.ERROR_DATA, INT p.INFO_CALIB_ACCURACY |
|
26 |
StopCalibRequest |
None |
INT p.ERROR_DATA |
|
19 |
ScanRequest |
INT p.VS_ID, BOOL p.HAND_EYE_ENABLE (if true, the current flange pose is sent with the request) |
INT p.ERROR_DATA |
|
30 |
CaptureRequest |
INT p.VS_ID (current flange pose read at call time with nullTool) |
INT p.ERROR_DATA |
|
31 |
ReuseScanRequest |
INT p.VS_ID |
INT p.ERROR_DATA |
|
20 |
GetObjectsRequest |
INT p.VS_ID, INT p.NUM_TAR_REQ |
INT p.ERROR_DATA, CPOS g.PHOTONEO_POSES[], INT p.NUM_TAR_RCV, INT p.INFO_OBJ_DIM_X, p.INFO_OBJ_DIM_Y, INT p.INFO_OBJ_ROT_Z, INT p.INFO_NN_LABEL, INT p.INFO_LAYER_MAX_Z, p.INFO_LAYER_TILT |
|
22 |
GetStatusRequest |
INT p.VS_ID |
INT p.ERROR_DATA, INT p.INFO_NUM_LOCALIZED, INT p.INFO_NUM_PICKABLE, INT p.INFO_VS_STATUS |
|
33 |
ChangeBBoxRequest |
INT p.VS_ID, INT p.BBOX_ID |
INT p.ERROR_DATA |
|
9 |
ChangeSolRequest |
INT p.SOL_ID |
INT p.ERROR_DATA |
|
10 |
StartSolRequest |
INT p.SOL_ID |
INT p.ERROR_DATA |
|
11 |
StopSolRequest |
None |
INT p.ERROR_DATA |
|
12 |
GetRunningSolRequest |
None |
INT p.ERROR_DATA, INT p.INFO_RUNNING_SOL |
|
100 |
ComCheckRequest |
None |
INT p.ERROR_DATA |
3.3 Pose Handling
Scan. ScanRequest triggers a scan and the localization on the vision system VS_ID. If HAND_EYE_ENABLE is true, the request first selects nullTool, reads the current flange pose and sends it with the scan (X, Y, Z in mm, A, B, C in radians). Use this for hand-eye (robot-mounted) sensors. For static sensors, leave HAND_EYE_ENABLE = false (default).
Get objects. GetObjectsRequest asks for up to NUM_TAR_REQ objects of the vision system VS_ID and stores them in g.PHOTONEO_POSES[1], g.PHOTONEO_POSES[2], … The number of received objects is stored in NUM_TAR_RCV.
Each pose is a Cartesian pose (CPOS) in the robot base frame: X, Y, Z in mm and A, B, C in degrees. The module converts the angles from radians.
The pose is the object pose. Move to it with your real tool (
Tool=t_g.toolPhotoneo). The tool must point to the gripping point.The Info data variables (section 3.4) are overwritten for each object, so after the request they hold the values of the last object received.
If
ERROR_DATAis not 0 (for example 202 - no object found), no new poses are received. Do not useg.PHOTONEO_POSESin that case.
Capture / Reuse scan. For hand-eye multi-view scanning (static meshing), call CaptureRequest in each view. It sends the current flange pose with nullTool. ReuseScanRequest runs the localization again on the last scan, without a new scan.
3.4 Info data
Info data are additional values sent with some responses (see Info data). The module stores each value in its own INT project variable, in the unit in which it was sent (no conversion). A variable keeps its value until the next response that contains the same key. The module also copies the raw values to INFO_DATA_ARR[] in the order of arrival.
Key |
Info data |
Variable |
Unit in robot |
Filled by |
|---|---|---|---|---|
4 |
Dimension X |
|
mm |
GetObjectsRequest |
5 |
Dimension Y |
|
mm |
GetObjectsRequest |
6 |
Rotation Z |
|
mrad |
GetObjectsRequest |
7 |
Neural network label |
|
integer |
GetObjectsRequest |
8 |
Max Z height |
|
mm |
GetObjectsRequest |
9 |
Tilt |
|
mrad |
GetObjectsRequest |
10 |
Calibration accuracy |
|
µm |
SaveCalibRequest |
11 |
Running solution ID |
|
integer |
GetRunningSolRequest |
12 |
Number of localized objects |
|
integer |
GetStatusRequest |
13 |
Number of ready objects |
|
integer |
GetStatusRequest |
14 |
Processing state |
|
0 / 1 |
GetStatusRequest |
The key numbers are stored in the constants CONST_INFO_* in prjglobal.erd. Do not change them.
3.5 Variables used by the module
All variables below are project variables in prjglobal.erd unless marked as global (g.).
Variable |
Type |
Description |
|---|---|---|
|
STRING |
IP address of the vision controller. Default 192.168.1.1. |
|
INT |
Port of the Action Request Server. Default 11003. |
|
STRING |
Brand ID |
|
Socket |
Socket used for the connection ( |
|
BOOL |
true = ScanRequest sends the current flange pose. Default false. |
|
INT |
Vision system ID for the next request. |
|
INT |
Solution ID for Change / Start Solution and Calibration Start. |
|
INT |
Bounding box ID for ChangeBBoxRequest. |
|
INT |
Number of objects requested by GetObjectsRequest. |
|
INT |
Number of objects received by GetObjectsRequest. |
|
CPOS array (global) |
Received object poses (mm, degrees). |
|
INT |
Error code of the last request. 0 = no error. |
|
INT |
Info data, see section 3.4. |
|
APOS |
Scanning pose used by the example programs. |
|
CPOS |
Drop pose and current pick pose used by the example programs. |
|
INT |
Request IDs and Info data keys. Do not change. |
Other variables in prjglobal.erd (MSG_*, ITERATOR*, FLANGE_*, …) are used internally by the request programs.
3.6 Error codes
The module does not define named error constants. Every request writes the error code from the vision controller to ERROR_DATA (0 = no error). For the meaning of each code, see Error codes. Examples: 202 (no object found), 222 (invalid bounding box) and 467 (calibration accuracy above the allowed threshold).
The module and the example programs raise the following robot alarms with SetRtToErr:
Alarm ID |
Message |
Raised by |
|---|---|---|
90001 |
Wrong Request ID / Wrong Operation Type |
Request programs, when the response does not belong to the request that was sent |
91001 |
Scan Error, Change BBox Error, Change Solution Error |
Example programs, when |
92001 |
Adding Calib Point Failed |
PhoCalibration, when CalibAddPointRequest fails |
3.7 Example Programs
The Photoneo Estun module contains several example programs. They show how to use the requests from section 3.2 in different use cases:
Estun Program |
Description |
|---|---|
|
Standard localization example. Shows the basic pick-and-place workflow. The program:
Error handling: If |
|
Calibration example. Shows automatic hand-eye calibration. Requirements: Calibration must be enabled in the vision system settings of Locator Studio. Calibration Steps:
Calibration Accuracy:
Automatic Recalibration (Optional):
|
|
Example with multiple vision systems. Same as PhoMainBasic, but alternates between two vision systems.
|
|
Example of bounding box switching. Same workflow as PhoMainBasic, with bounding box selection.
Error handling for |
|
Example of solution switching. Same workflow as PhoMainBasic, with solution management.
At the start, the program calls
Error handling for |
Listing of PhoMainBasic.erp:
// InstParseVersion: V1.02
Start:
SetDO{IO=t_g.ventil,Val=0}
--Move to scanning pose
MovJ{P=t_p.SCAN}
---
--Establish Connection to Vision Controller
---
SocketCreate{socketName=t_p.PhotoneoSocket,IP=t_p.PHOTONEO_IP.value,Port=t_p.PHOTONEO_PORT.value,Ret=t_p.SOCKET_RETVAL}
SocketSendStr{socketName=t_p.PhotoneoSocket,stringData=t_p.ESTUN_ID,Ret=t_p.SOCKET_RETVAL}
Wait{T=10}
---
--Scan Request
---
scan:
t_p.VS_ID.value = 1
t_p.ERROR_DATA.value = 0
CALL ScanRequest
--If scan fails, go to program end
IF ( t_p.ERROR_DATA.value ~= 0 ) THEN
SetRtToErr{msg="Scan Error",eid=91001}
GOTO prog_end
ENDIF
---
--Get Objects Request
---
get_objects:
t_p.VS_ID.value = 1
t_p.NUM_TAR_REQ.value = 15
t_p.ERROR_DATA.value = 0
CALL GetObjectsRequest
--If no targets found wait and repeat scan
IF ( t_p.ERROR_DATA.value ~= 0 ) THEN
Wait{T=1000}
GOTO scan
ELSE
GOTO pick
ENDIF
---
--Execute picks
---
pick:
FOR t_l.ITER.value = 1 , t_l.ITER.value <= t_p.NUM_TAR_RCV.value , t_l.ITER.value = t_l.ITER.value + 1 DO
--Pick
t_p.pickPhotoneo = t_g.PHOTONEO_POSES [ t_l.ITER.value ]
MovLOffsetC{RP=t_p.pickPhotoneo,TPX=0,TPY=0,TPZ=50,TPA=0,T="COORD",Tool=t_g.toolPhotoneo,Coord=t_s.World,V=t_s.V1000,B="RELATIVE",C=t_s.C30}
MovL{P=t_p.pickPhotoneo,V=t_s.V100,B="FINE",Tool=t_g.toolPhotoneo}
SetDO{IO=t_g.ventil,Val=1}
Wait{T=200}
MovLOffsetC{RP=t_p.pickPhotoneo,TPX=0,TPY=0,TPZ=50,TPA=0,T="COORD",Tool=t_g.toolPhotoneo,Coord=t_s.World,V=t_s.V2000,B="RELATIVE",C=t_s.C20}
--Drop
MovLOffsetC{RP=t_p.DROP_UP,TPX=0,TPY=0,TPZ=250,TPA=0,T="COORD",Tool=t_g.toolPhotoneo,Coord=t_s.World,V=t_s.V1000,B="RELATIVE",C=t_s.C20}
MovL{P=t_p.DROP_UP,V=t_s.V1000,Tool=t_g.toolPhotoneo}
SetDO{IO=t_g.ventil,Val=0}
Wait{T=50}
MovLOffsetC{RP=t_p.DROP_UP,TPX=0,TPY=0,TPZ=250,TPA=0,T="COORD",Tool=t_g.toolPhotoneo,Coord=t_s.World,V=t_s.V1000,B="RELATIVE",C=t_s.C100}
ENDFOR
---
--Jump back to scan label
GOTO scan
---
prog_end:
SocketResetBuf{socketName=t_p.PhotoneoSocket}
SocketClose{socketName=t_p.PhotoneoSocket,Ret=t_p.SOCKET_RETVAL}
End;
4. Runtime
When the solution is fully configured on the vision controller, finish the remaining steps on the robot side and run the PhoMainBasic program.
4.1 Teach Positions
After you open PhoMainBasic or another example program, touch up the project SCAN pose and a few other poses before you run the program. You can modify SCAN directly in Project Data → APOS →SCAN.
The drop pose DROP_UP is a project CPOS variable. Modify it in the standard way. In the drop logic, define the approach point offsets directly in the code (MovLOffsetC with TPZ). They set the direction from which the robot approaches the drop point.
4.2 Gripper Commands
The Locator Studio module has no gripper procedures by default. The example programs switch the global digital output g.ventil directly. Adapt this to your gripper at the correct places in the program. See the example below:
Use the DIO commands that activate your gripper, for example simple 24 V IO or fieldbus commands. If needed, add a delay between activating the signal and the physical attachment of the part.
4.3 Calibration
Locator Studio has 3 calibration methods:
Sphere-based calibration - for statically mounted sensors
Marker-pattern-based calibration - for robot-mounted (hand-eye) sensors
Marker-pattern-based calibration - for static sensors and user / work object calibration
For the first two methods, capture the calibration object from 9 poses with enough variation in the tool pose. Always use the zero tool and user frame as the default frames. Non-zero frames can give wrong calibration results.
The third method (marker-pattern-based calibration for static sensors) needs only one scan. The main difference from the first two methods: the origin of the scene is not the robot origin, but the origin of the marker pattern. The third method cannot be automated. You must do it manually.
You can calibrate without a robot program. Start the calibration in LS, jog the robot from point to point and add the points manually in LS (type the TCP values from the teach pendant into the calibration pop-up window). To avoid typing the values, use a robot program. For the very first calibration, start the process manually in LS, but add the points with the PhoCalibration program. Teach all 9 calibration poses and then step through the program. PhoCalibration connects to the vision controller and triggers a scan in each calibration point. For fully automatic recalibration, PhoCalibration can start, save and stop the calibration directly from the robot program. This needs a first manual calibration and automatic recalibration enabled on the Calibration tab of the vision system. Comment or uncomment the Calib Start / Calib Save / Calib Stop parts of the code to switch between semi-automatic and fully automatic calibration.
The PhoCalibration program works in these steps:
Start - connect to the vision controller and call
StartCalibRequest(SOL_ID,VS_ID). Commented out by default.Add points - move to
CALIB_POSE_1…CALIB_POSE_9and callCalibAddPointRequestin each pose. The request selects nullTool, reads the current flange pose and sends it.Save - call
SaveCalibRequest. Commented out by default. The calibration accuracy is stored inINFO_CALIB_ACCURACY(µm).Stop - call
StopCalibRequest. Commented out by default. The socket is then closed.
In general, the calibration error should be below 3 mm. If the error is higher, check the most common causes: wrong tool frame values, wrong gripper model orientation, wrong robot model, encoder zeroing and an unstable robot base.
4.4 Runtime Prerequisites
Do a final check before you start the Locator Studio program on the robot.
Make sure that:
The Locator Studio solution is correctly configured on the vision controller.
The network setup on the robot side is complete (and the Robot State Server works, if installed).
The global variables from section 2.5 are created.
All vision systems in the solution are calibrated.
All poses in the main program are touched up.
The gripper commands are ready and working.
4.5 Running PhoMainBasic
Deploy your solution. Until the communication is established, the Deployment page shows the Action Request Client (Robot) status as DISCONNECTED.
Note
Before you run the program for the first time, we strongly recommend that you decrease the override speed to 5%.
When the connection is established, the Action Request Client status (and the Robot State Server status, if installed) changes to CONNECTED. The sensor should then capture the first scan, and the localization should start.
If there is a pickable object in the scene and the robot controller has received its Cartesian pose, the robot should start moving towards the object.
If everything looks fine, let the robot continue towards the first object and check that the path is correct. If the robot stops too far from the object or pushes it too deep, adjust the object origin or the tool TCP setup.
If the robot movement looks fine, set up your own placing routine and slowly increase the speed back to 100%. You have successfully deployed the Photoneo Estun Robot module. You can now improve your application further. Use the cheat sheet and the example programs as a guide.
5. Troubleshooting and error handling
Request failed - every request writes the error code from the vision controller to
ERROR_DATA. Check it after eachCALLand handle the error in your program. PhoMainBasic stops with an alarm when the scan fails and scans again when Get Objects fails. See Error codes.Response timeout - the request programs wait up to 15 s for the first response line of Scan, up to 5 s for the other requests and up to 0.5 s for each following line. If the vision controller does not answer, check that the solution is deployed and that the connection on the Deployment page is green.
Alarm 90001 Wrong Request ID - the response does not belong to the request that was sent, usually because an earlier request was interrupted. Restart the main program. It opens a new connection.
No connection - check
PHOTONEO_IPandPHOTONEO_PORT(11003), the network setup (section 2.2) and that only one robot program uses the socket.Robot misses the object - check that
g.toolPhotoneomatches the real tool and that scanning and calibration were done with nullTool.
6. Version and brand ID
Item |
Value |
|---|---|
Robot module version |
1.5.0 ( |
Locator Studio |
1.5 |
Brand ID ( |
|
Action Request Server port |
11003 |
7. Migration
Changes from the Estun LS module 1.4 to 1.5:
The module folder was renamed from
ESTUN_LS_1_4_0.ertoESTUN_LS_1_5_0.erandESTUN_IDchanged toESTUN/L/1.5.0XXXXXXXXXXX.Info data are stored in named variables (
INFO_OBJ_DIM_X,INFO_NN_LABEL,INFO_RUNNING_SOL, …) instead of positions inINFO_DATA_ARR.New: the requests
ReuseScanRequest,StartSolRequestandStopSolRequest, theHAND_EYE_ENABLEswitch and the example programPhoMainChangeSol.
See Migration from LS 1.4.x to LS 1.5.x for all changes in the communication interface.